/*
Package ratelimit implements rate limiting functionality for the proxy.

It provides per process rate limiting. It can be
configured globally, or based on routes. Rate limiting can be lookuped
based on HTTP headers for example X-Forwarded-For or Authorization.

# Lookuper Type - SameBucketLookuper

This lookuper will use a static string to point always to the same
bucket. This means all requests are counted the same.

# Lookuper Type - HeaderLookuper

This lookuper will use the content of the the specified header to
calculate rate limiting.

# Lookuper Type - XForwardedForLookuper

This lookuper will use the remote IP of the origin request to
calculate rate limiting. If there is no such header it will use the
remote IP of the request. This is the default Lookuper and may be the
one most users want to use.

# Usage

When imported as a package, the Registry can be used to hold the rate
limiters and their settings. On a higher level, rate limiter settings
can be simply passed to skipper as part of the skipper.Options object,
or defined as command line flags.

The following command starts skipper with default X-Forwarded-For
Lookuper, that will start to rate limit after 5 requests within 60s
from the same client

	% skipper -ratelimits type=client,max-hits=5,time-window=60s

The following configuration will rate limit /foo after 2 requests
within 90s from the same requester and all other requests after 20
requests within 60s from the same client

	% cat ratelimit.eskip
	foo: Path("/foo") -> clientRatelimit(2,"1m30s") -> "http://www.example.org/foo"
	rest: * -> clientRatelimit(20,"1m") -> "http://www.example.net/"
	% skipper -enable-ratelimits -routes-file=ratelimit.eskip

The following configuration will rate limit requests after 100
requests within 1 minute with the same Authorization Header

	% cat ratelimit-auth.eskip
	all: * -> clientRatelimit(100,"1m","Authorization") -> "http://www.example.org/"
	% skipper -enable-ratelimits -routes-file=ratelimit-auth.eskip

The following configuration will rate limit requests to /login after 10 requests
summed across all skipper peers within one hour from the same requester.

	% cat ratelimit.eskip
	foo: Path("/login") -> clientRatelimit(10,"1h") -> "http://www.example.org/login"
	rest: * -> "http://www.example.net/"
	% skipper -enable-ratelimits -routes-file=ratelimit.eskip -enable-swarm

Rate limiter settings can be applied globally via command line flags
or within routing settings.

# Settings - Type

Defines the type of the rate limiter. There are types that only use
local state information and others that use cluster information using
swarm.Swarm or redis ring shards to exchange information. Types that
use instance local information are ServiceRatelimit to be used to
protect backends and ClientRatelimit to protect from too chatty
clients. Types that use cluster information are
ClusterServiceRatelimit to be used to protect backends and and
ClusterClientRatelimit to protect from too chatty
clients. ClusterClientRatelimit using swarm should be carefully tested
with your current memory settings (about 15MB for 100.000 attackers
per filter), but the use cases are to protect from login attacks, user
enumeration or DDoS attacks. ClusterServiceRatelimit and
ClusterClientRatelimit using redis ring shards should be carefully
tested, because of redis. Redis ring based cluster ratelimits should
not create a significant memory footprint for skipper instances, but
might create load to redis.

# Settings - MaxHits

Defines the maximum number of requests per user within a TimeWindow.

# Settings - TimeWindow

Defines the time window until rate limits will be enforced, if maximum
number of requests are exceeded. This is defined as a string
representation of Go's time.Duration, e.g. 1m30s.

# Settings - Lookuper

Defines an optional configuration to choose which Header should be
used to group client requests. It accepts any header, for example
"Authorization".

# Settings - Group

Defines the ratelimit group, which can be the same for different
routes, if you want to have one ratelimiter spanning more than one
route. Make sure your settings are the same for the whole group. In
case of different settings for the same group the behavior is
undefined and could toggle between different configurations.

# HTTP Response

In case of rate limiting, the HTTP response status will be 429 Too
Many Requests and two headers will be set.

One which shows the maximum requests per hour:

	X-Rate-Limit: 6000

And another indicating how long (in seconds) to wait before making a new
request:

	Retry-After: 3600

Both are based on RFC 6585.

# Registry

The active rate limiters are stored in a registry. They are created
based on routes or command line flags. The registry synchronizes
access to the shared rate limiters. A registry has default settings
that it will apply and that it will use the disable rate limiter in
case it's not defined in the configuration or not global enabled.
*/
package ratelimit
